package com.ease.util {

import flash.events.Event;

[SDK]
/**
 * Represents the addition or removal of an object from the system. Certain classes of
 * objects such as display objects are notified through other means, so this event is
 * mostly useful for object types that are not already taken care of by flex framework
 * events.
 *
 * <p>SDK Version 1.0.0</p>
 */
public class ObjectEvent extends Event
{
   /**
    * Event type id for notifying the addition of an object to the system.
    */
   public static const OBJECT_ADDED:String = "objectAdded";

   /**
    * Event type id for notifying the removal of an object from the system.
    */
   public static const OBJECT_REMOVED:String = "objectRemoved";

   /**
    * Initializes an instance of this class.
    *
    * @param type
    *    The id for the event.
    * @param object
    *    Value for the object property.
    */
   public function ObjectEvent( type:String, object:Object = null,
                                bubbles:Boolean = true ) {
      super( type, bubbles );
      _object = object;
   }

   /**
    * Creates a clone of this event. All custom events should override this method.
    *
    * @return
    *    A clone of this event.
    */
   public override function clone():Event {
      var ev:ObjectEvent = new ObjectEvent( super.type, _object, super.bubbles );
      ev.isWeakReferencingMandatory = _isWeakReferencingMandatory;
      return ev;
   }

   //---------------------------------------------------------------------------
   // Class Methods

   /**
    * A convenience factory method to create an instance of this class that represents
    * the addition of a new object to the system.
    */
   public static function newRemoval( object:Object ):ObjectEvent {
      return new ObjectEvent( OBJECT_REMOVED, object );
   }

   /**
    * A convenience factory method to create an instance of this class that represents
    * the removal of an existing object from the system.
    */
   public static function newAddition( object:Object,
                                       useWeakReference:Boolean = false ):ObjectEvent {
      var event:ObjectEvent = new ObjectEvent( OBJECT_ADDED, object );
      event.isWeakReferencingMandatory = useWeakReference;
      return event;
   }

   //-------------------------------------------------------
   // Property: object

   private var _object:Object;

   /**
    * The object whose addition or removal from the system is being notified.
    */
   public function get object():Object {
      return _object;
   }

   //-------------------------------------------------------
   // Property: isWeakReferencingMandatory

   private var _isWeakReferencingMandatory:Boolean = false;

   /**
    * This property is meaningful only for an <code>objectAdded</code> event and indicates
    * to the recipients of this event (e.g., platform services) whether they are required
    * to reference the object through weak-references only.
    *
    * <p>If this flag is set to true, the object should become a candidate for garbage
    * collection once the client removes all its references to the object; in other words,
    * the client should never have to raise the <code>objectRemoved</code> event for the
    * said object. The services that require strong-referencing of the object will not be
    * provided for this object.
    *
    * <p>The default value of this property is false.
    */
   public function get isWeakReferencingMandatory():Boolean {
      return _isWeakReferencingMandatory;
   }

   public final function set isWeakReferencingMandatory( value:Boolean ):void {
      _isWeakReferencingMandatory = value;
   }
} // class

}